home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audiofile / AFopenfile.z / AFopenfile
Encoding:
Text File  |  1998-10-20  |  10.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))                                                aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afOpenFile, afOpenFD, afOpenNamedFD - allocate an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure
  10.      for an audio file identified by name / by a Unix file descriptor
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  16.                              AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp sssseeeettttuuuupppp))))
  17.  
  18.      AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee aaaaffffOOOOppppeeeennnnFFFFDDDD((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  19.                            AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp sssseeeettttuuuupppp))))
  20.  
  21.      AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee aaaaffffOOOOppppeeeennnnNNNNaaaammmmeeeeddddFFFFDDDD((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  22.                                 AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp sssseeeettttuuuupppp,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr**** nnnnaaaammmmeeee))))
  23.  
  24. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  25.      _n_a_m_e    A character string which names the audio file to be opened.
  26.  
  27.      _f_d      A Unix file descriptor corresponding to an audio data file which
  28.              has been previously returned by ooooppppeeeennnn(2) or its equivalent.
  29.  
  30.      _m_o_d_e    This parameter identifies whether the file is to be opened for
  31.              reading or writing audio sample data and header information.
  32.              Acceptable values:
  33.  
  34.              """"rrrr"""" configures the file descriptor for read-only access
  35.  
  36.              """"wwww"""" configures the file descriptor for write-only access
  37.  
  38.              The current library implementation causes existing files to be
  39.              truncated to zero length and rewritten when opened for write
  40.              access.
  41.  
  42.      _s_e_t_u_p   is an AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp structure previously returned by a call to
  43.              aaaaffffNNNNeeeewwwwFFFFiiiilllleeeeSSSSeeeettttuuuupppp(3dm).  _s_e_t_u_p contains initialization parameters
  44.              used by aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(((()))) when it configures a new AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee, and
  45.              initializes the corresponding file header.  _s_e_t_u_p is generally
  46.              set to NULL when _m_o_d_e is """"rrrr"""".
  47.  
  48.              If _s_e_t_u_p is non-NULL and _m_o_d_e is """"rrrr"""", it indicates a desire to
  49.              read an audio file as a raw (headerless) file.  The _s_e_t_u_p
  50.              structure's file format parameter must be set to AAAAFFFF____FFFFIIIILLLLEEEE____RRRRAAAAWWWWDDDDAAAATTTTAAAA,
  51.              and all its parameters must be initialized to acceptable values
  52.              prior to the call to the afOpen routine.  This is done with
  53.              aaaaffffIIIInnnniiiittttFFFFiiiilllleeeeFFFFoooorrrrmmmmaaaatttt(3dm), aaaaffffIIIInnnniiiittttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm),
  54.              aaaaffffIIIInnnniiiittttCCCChhhhaaaannnnnnnneeeellllssss(3dm), aaaaffffIIIInnnniiiittttRRRRaaaatttteeee(3dm), etc.  If this is not done,
  55.              aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(((()))), etc.  will return an error.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))                                                aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74. RETURNED VALUE
  75.      If successful, each function returns an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure for the
  76.      named file.  A null (AAAAFFFF____NNNNUUUULLLLLLLL____FFFFIIIILLLLEEEEHHHHAAAANNNNDDDDLLLLEEEE) return value indicates an error.
  77.  
  78.      aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(((()))), aaaaffffOOOOppppeeeennnnFFFFDDDD(((()))), and aaaaffffOOOOppppeeeennnnNNNNaaaammmmeeeeddddFFFFDDDD(((()))) return null AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee
  79.      structures when a file opened with mode """"rrrr"""" does not parse according to
  80.      any of the implemented file format specifications.
  81.  
  82. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  83.      aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(((()))) allocates and initializes an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure for an
  84.      audio file.  This structure is then used as the basic argument for all
  85.      Audio File Library routines which access data in the audio file.
  86.  
  87.      The audio track logical read/write pointer used by aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(3dm) and
  88.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(3dm) is initialized to point to the location of the first
  89.      sample in the audio file.
  90.  
  91.      aaaaffffOOOOppppeeeennnnFFFFDDDD(((()))) allows you to test whether a file can be opened for reading or
  92.      writing using regular Unix system calls before attempting to attach an
  93.      AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure to the file.  This can help you eliminate error
  94.      messages from the Audio File Library in some cases. aaaaffffOOOOppppeeeennnnNNNNaaaammmmeeeeddddFFFFDDDD(((()))) must
  95.      be used in place of aaaaffffOOOOppppeeeennnnFFFFDDDD(3dm) if any of the files to be identified
  96.      are Sound Designer II files.  This is due to the multi-file nature of the
  97.      format (resource and data fork files at a minimum), and so the full path
  98.      to the file must be known to properly identify its format.  See ssssdddd2222(4)
  99.      for more information.
  100.  
  101. NNNNOOOOTTTTEEEE
  102.      The current Audio File Library does not support read-write (or "edit")
  103.      access for existing files.  In order to edit an existing file through the
  104.      library, it is necessary to create a second version of the file.
  105.  
  106.      Sample source code in /_u_s_r/_s_h_a_r_e/_s_r_c/_d_m_e_d_i_a/_s_o_u_n_d_f_i_l_e shows how to make a
  107.      copy of an audio file which contains all the logical components of the
  108.      original file.
  109.  
  110. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  111.      Many of the routines in the Audio File Library will not function
  112.      correctly if the user changes the file position on the file descriptor
  113.      for the AFfilehandle being manipulated.  See the section _C_A_V_E_A_T_S _F_O_R
  114.      _U_S_I_N_G _T_H_E _H_A_N_D_L_E'_S _F_I_L_E _D_E_S_C_R_I_P_T_O_R in aaaaffffIIIInnnnttttrrrroooo(3dm) for some important
  115.      information about how to deal with this situation Be careful when using
  116.      aaaaffffOOOOppppeeeennnnFFFFDDDD(((()))):  Regardless of whether a file is opened with aaaaffffOOOOppppeeeennnnFFFFDDDD(((()))),
  117.      aaaaffffOOOOppppeeeennnnNNNNaaaammmmeeeeddddFFFFDDDD(((()))), or aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(((()))), its file descriptor will be closed when
  118.      the user issues aaaaffffCCCClllloooosssseeeeFFFFiiiilllleeee(3dm). Do not expect the file descriptor to
  119.      remain open just because it was opened by an external function call.
  120.      This is unfortunately not consistent with the SGI Movie Library, but must
  121.      be maintained for backwards compatibility.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))                                                aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140. SEE ALSO
  141.      afCloseFile(3dm), afNewFileSetup(3dm), afReadFrames(3dm),
  142.      afWriteFrames(3dm) afInitFileFormat(3dm)
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.